postcss-nesting

What is postcss-nesting?

The postcss-nesting package is a PostCSS plugin that allows you to use nesting syntax in CSS, similar to what is offered by preprocessors like Sass and Less. It helps to write more readable and maintainable CSS by allowing styles to be nested within one another.

What are postcss-nesting's main functionalities?

Nesting Rules

Allows nesting of selectors within a parent selector, which will be expanded to the equivalent of 'a b { color: black; }'.

a {
  & b { color: black; }
}

Nesting Properties

Enables nesting of properties, which is useful for grouping font properties or other related properties together.

a {
  font: {
    weight: bold;
    size: 1em;
    family: serif;
  }
}

Nesting At-Rules

Supports nesting of at-rules like @media within a selector, which will be processed into the correct CSS syntax.

a {
  @media (min-width: 500px) {
    color: black;
  }
}

Other packages similar to postcss-nesting

postcss-nested

Similar to postcss-nesting, postcss-nested allows for nesting of selectors within CSS. It follows the nesting rules of preprocessors like Sass rather than the CSS Nesting Module.

postcss-preset-env

This package includes postcss-nesting as one of its features, among other future CSS features, and allows you to use them in current browsers.

postcss-scss

This is a syntax plugin for PostCSS that allows you to work with SCSS syntax, including nesting, but it does not compile SCSS. It's useful for linting SCSS with stylelint and PostCSS.

README

PostCSS Nesting

npm install postcss-nesting --save-dev

PostCSS Nesting lets you nest style rules inside each other, following the CSS Nesting specification.

If you want nested rules the same way Sass works you might want to use PostCSS Nested instead.

.foo {
	color: red;

	&:hover {
		color: green;
	}

	> .bar {
		color: blue;
	}

	@media (prefers-color-scheme: dark) {
		color: cyan;
	}

	color: pink;
}

/* becomes */

.foo {
	color: red;

	color: pink;
}
.foo:hover {
		color: green;
	}
.foo > .bar {
		color: blue;
	}
@media (prefers-color-scheme: dark) {
	.foo {
		color: cyan;
}
	}

Usage

Add PostCSS Nesting to your project:

npm install postcss postcss-nesting --save-dev

Use it as a PostCSS plugin:

const postcss = require('postcss');
const postcssNesting = require('postcss-nesting');

postcss([
	postcssNesting(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);

PostCSS Nesting runs in all Node environments, with special instructions for:

• Node
• PostCSS CLI
• PostCSS Load Config
• Webpack
• Next.js
• Gulp
• Grunt

⚠️ @nest has been removed from the specification.

Previous iterations of the CSS Nesting specification required using @nest for certain selectors.

@nest was removed from the specification completely. Future versions of this plugin will error if you use @nest.

We advice everyone to migrate their codebase now to nested CSS without @nest.
We published a Stylelint Plugin to help you migrate.

example warning:

@nest was removed from the CSS Nesting specification and will be removed from PostCSS Nesting in the next major version. Change @nest foo & {} to foo & {} to migrate to the latest standard.

You can silence this warning with a new silenceAtNestWarning plugin option.

postcssNesting({
	silenceAtNestWarning: true
})

Options

edition

The default behavior is to transpile CSS following an older version of the CSS nesting specification.

If you want to already use the latest version you can set the edition option to 2024-02.

postcssNesting({
	edition: '2024-02'
})

2021 (default)

This version is a continuation of what existed before CSS nesting was implemented in browsers.
It made a few non-invasive changes to keep up with implementations but it is falling behind.

In a future version of this plugin this will no longer be the default.

.foo {
	color: red;

	&:hover {
		color: green;
	}

	> .bar {
		color: blue;
	}

	@media (prefers-color-scheme: dark) {
		color: cyan;
	}

	color: pink;
}

/* becomes */

.foo {
	color: red;

	color: pink;
}
.foo:hover {
		color: green;
	}
.foo > .bar {
		color: blue;
	}
@media (prefers-color-scheme: dark) {
	.foo {
		color: cyan;
}
	}

2024-02

• usage of :is() pseudo-class is no longer optional
• at rules are not combined with the and keyword
• @nest is removed from the specification
• declarations and nested rules/at-rules are no longer re-ordered

.foo {
	color: red;

	&:hover {
		color: green;
	}

	> .bar {
		color: blue;
	}

	@media (prefers-color-scheme: dark) {
		color: cyan;
	}

	color: pink;
}

/* becomes */

.foo {
	color: red;
}
.foo:hover {
		color: green;
	}
.foo  > .bar {
		color: blue;
	}
@media (prefers-color-scheme: dark) {
	.foo {
		color: cyan;
}
	}
.foo {

	color: pink;
}

noIsPseudoSelector

Specificity

Before :

#alpha,
.beta {
	&:hover {
		order: 1;
	}
}

After without the option :

postcssNesting()

:is(#alpha,.beta):hover {
	order: 1;
}

.beta:hover has specificity as if .beta where an id selector, matching the specification.

specificity: 1, 1, 0

After with the option :

postcssNesting({
	noIsPseudoSelector: true
})

#alpha:hover, .beta:hover {
	order: 1;
}

.beta:hover has specificity as if .beta where a class selector, conflicting with the specification.

specificity: 0, 2, 0

Complex selectors

Before :

.alpha > .beta {
	& + & {
		order: 2;
	}
}

After without the option :

postcssNesting()

:is(.alpha > .beta) + :is(.alpha > .beta) {
	order: 2;
}

After with the option :

postcssNesting({
	noIsPseudoSelector: true
})

.alpha > .beta + .alpha > .beta {
	order: 2;
}

this is a different selector than expected as .beta + .alpha matches .beta followed by .alpha.
avoid these cases when you disable :is()
writing the selector without nesting is advised here

/* without nesting */
.alpha > .beta + .beta {
	order: 2;
}